Cloudflare Pages Deployment & SSO

Architecture, Automation, and Security Guide

1. System Overview

This project transitioned from a local Docker-based Caddy server to a distributed, edge-hosted solution on Cloudflare Pages. Access is restricted via Cloudflare Zero Trust (Access) using an SSO provider, ensuring that only authorized personnel can view the documentation.

Key URL: https://notes.synactic.com

2. Architecture & Components

  • Static Hosting: Cloudflare Pages (Direct Upload mode).
  • Search Engine: Pagefind (Static indexer built locally).
  • Security: Cloudflare Access (SSO via Google/Synactic).
  • Automation: Custom shell scripts and Node.js dashboard generator.

3. The Build & Deployment Pipeline

The deployment is handled entirely from the local machine using the deploy.sh script. This bypasses the need for a Git-based CI/CD pipeline while maintaining a consistent build environment.

Step A: Dashboard Generation

generate_tree.js scans the directory structure and creates a responsive index.html. It also gathers metadata for the "Newest Notes" and "Date Picker" features.

Step B: Search Indexing

Pagefind scans the HTML content and builds a highly optimized binary search index in the /pagefind directory.

Step C: Wrangler Deployment

The Wrangler CLI uploads the entire directory (respecting .wranglerignore) to Cloudflare's edge network.

# The primary command for updates:
./deploy.sh

4. Key Configuration Files

deploy.sh

Orchestrates the build and push. It loads credentials from .env and runs generate_tree.js followed by pagefind and wrangler.

cf_setup.sh

A one-time setup script using Cloudflare's API to configure DNS, create the Pages project, and establish the Zero Trust Access Application.

.env

Stores sensitive credentials. Never commit this file.

CLOUDFLARE_ACCOUNT_ID=...
CLOUDFLARE_ZONE_ID=...
CLOUDFLARE_EMAIL=...
CLOUDFLARE_API_KEY=...

5. Mobile Optimization

All pages are optimized for mobile via a one-time sweep that injected the viewport meta tag into the <head> of every HTML file. The dashboard uses Tailwind CSS with a responsive grid system to adapt to small screens.

6. Troubleshooting Guide

401 Unauthorized Errors

If you see a 401 error, check the Cloudflare Access policies. Ensure the user's email domain is included in the "Synactic Domain Access" policy or explicitly added as a user.

Redirection Loops

Usually caused by a mismatch between the Access Application domain and the DNS record. Ensure the DNS CNAME record for notes points to synactic-notes.pages.dev and is Proxied (Orange Cloud).

New Notes Not Appearing

Ensure you ran ./deploy.sh after adding the note. If the note is there but not in search, check if the file ends in .html and that pagefind successfully indexed it during the last run.

Deployment Failures

Check if your .env variables are correct and that you have npx installed. Run npx wrangler whoami to verify authentication.